‼️ On macOS, netstat -ltn succeeds but includes non-listening TCP states. This branch only checks whether the complete output contains any LISTEN, then scans every token in every row, so an unrelated ESTABLISHED peer port can be mistaken for a local listener. I reproduced this on macOS: no listener existed on 443 (lsof -iTCP:443 -sTCP:LISTEN was empty), but an outbound connection to :443 made check_port "http://0.0.0.0:443" exit 1. Please select the parser by OS and inspect only the local-address field of LISTEN rows; a conservative port-only comparison is sufficient here.

Fixed in 5f4a70d1.

The parser no longer scans every token in every row. Detection is now OS-selected and inspects only LISTEN rows and only the local-address column:

• macOS/BSD: netstat -an -p tcp, rows filtered on $NF == "LISTEN"
• Linux: ss -H -ltn (already listen-only), falling back to netstat -ltn

The address is split on its last separator, so an IPv6 hextet such as [2001:db8:8080::1]:9090 can no longer be read as port 8080.

Reproduced your case on macOS before and after. With 37 ESTABLISHED connections to :443 and netstat -an -p tcp | awk '$NF=="LISTEN" && $4 ~ /\.443$/' empty:

before: check_port "http://0.0.0.0:443"  ->  "The port 443 has already been used", exit 1
after : check_port "http://0.0.0.0:443"  ->  exit 0 (free)

Per your note that a conservative port-only comparison is sufficient, I also took the rest of the minimal design: DNS resolution, address canonicalization, cross-family matching, /dev/tcp and its watchdog are removed, and the result is now busy / free / unknown.

Two regressions in the suite cover this specifically: a TIME_WAIT row whose local port is the target must read free, and a row where only the foreign address carries the port must read free. Both fail if the LISTEN filter or the column restriction is removed — I verified that by mutation rather than assuming.

⚠️ A failed atomic rename is overwritten by the unconditional return 0 below, so callers can export LD_PRELOAD as if the verified library were installed even when mv failed. Keep this simple: mv -f -- "$tmp" "$filepath" || { rm -f -- "$tmp"; return 1; }, and add one rename-failure test.

Fixed in 5f4a70d1, using your suggestion as written:

mv -f -- "$tmp" "$filepath" || { rm -f -- "$tmp"; return 1; }

The unconditional return 0 is gone, so a failed rename can no longer make callers export LD_PRELOAD for a library that never installed.

The same bug was present in download() in all three copies (server, PD, store) — the rename there was also unchecked — so it is fixed in each.

Covered by a rename-failure test that stubs mv to fail and asserts three things: download returns non-zero, no destination file is left behind, and the temp file is cleaned up.

⚠️ parse_port_from_url() converts the digit string before bounding its size, so Bash integer overflow can turn an invalid configured port into a valid one. On this exact head, parse_port_from_url "http://127.0.0.1:18446744073709551617" prints 1 and returns 0 because $((10#$port)) wraps before the 1..65535 check; the 44-case suite only covers 70000. Please strip leading zeroes and reject values longer or lexically larger than 65535 before arithmetic conversion, then add an oversized-integer regression.

Confirmed and fixed in a413325b. Your repro is correct, and the case is a bit wider than the value you found.

18446744073709551617 wraps to 1, but the worse shape is a value that wraps into a plausible port:

before: parse_port_from_url "http://127.0.0.1:18446744073709559616"  ->  8000
after : rc=1 (skipped)

That one mattered more than the wrap to 1: the preflight would have aborted startup with "The port 8000 has already been used", naming a port the operator never configured, for what is really a malformed value.

The fix normalises the leading-zero form textually and bounds the digit count before any arithmetic:

port="${port#"${port%%[!0]*}"}"
[[ -z "$port" ]] && return 1
(( ${#port} <= 5 )) || return 1
(( port >= 1 && port <= 65535 )) || return 1

Leading zeroes are still accepted, since new URI("http://127.0.0.1:0000000000000008080").getPort() returns 8080 — I checked rather than assumed. 00000 returns 0 there and is skipped.

Four cases added to the URL-parsing table: both wrapping values, 00000, and the long leading-zero form. The suite is 48 passed, 0 failed, and restoring port=$((10#$port)) fails exactly the two overflow cases, so they are not vacuous.

⚠️ This unknown path is now the normal path in the official server images: both hugegraph-server/Dockerfile variants install lsof, but neither installs ss (iproute2) nor netstat (net-tools). The image therefore loses the occupied-port preflight even though it still ships the old probe dependency; a duplicate start can overwrite bin/pid before the new JVM fails to bind, leaving the original process unmanaged by the stop script. Please retain an lsof fallback or update the image dependency to a supported socket-table tool, and add an image-level duplicate-start/stop test.

Confirmed, and it is worse than a lost warning. Checked the base image rather than reasoning about it:

$ docker run --rm eclipse-temurin:11-jre-jammy \
    bash -c 'for t in ss netstat lsof ip; do printf "%-8s " $t; command -v $t || echo MISSING; done'
ss       MISSING
netstat  MISSING
lsof     MISSING
ip       MISSING

So the image installs lsof for a probe nothing calls any more, and ships nothing the new probe can use. Against a real listener, sourcing the exact-head util.sh inside that image:

as shipped (lsof):    port 8080 -> unknown    port 9999 -> unknown
with iproute2:        port 8080 -> busy       port 9999 -> free

Fixed in d93b6f9d by taking the second option you offered: lsof is replaced with iproute2 in hugegraph-server/Dockerfile and Dockerfile-hstore. Retaining an lsof fallback would put back the call whose fd-table scan is the hang this PR exists to fix, and it would be reached exactly where it hurts — a container with a large ulimit -n.

Flagging one judgement call: I removed lsof rather than keeping it alongside iproute2. Nothing shipped calls it (checksocket.sh shells out to CheckSocket, docker-entrypoint.sh does not use it), so it was only a debugging convenience like vim. Say the word if you would rather keep both.

On the image-level test: the cheap half is in, the expensive half is not. docker-build-ci.yml already builds each Dockerfile on any PR touching **/Dockerfile*, so it now asserts the probe can answer inside the built image:

STATE=$(docker run --rm "$IMAGE_ID" bash -c \
  'source /hugegraph-server/bin/util.sh && port_listen_state 8080')
[[ "$STATE" != "unknown" ]] || { echo "ERROR: no usable socket-table tool"; exit 1; }

That pins the dependency, not the duplicate-start behaviour it protects. A real duplicate-start/stop check needs a booted server with a backend, which belongs with the e2e job rather than the image build — left as TODO(docker-ci) in the workflow rather than half-done here.

⚠️ A successful but unparseable ss response returns unknown here immediately, so a working netstat fallback is never consulted. For example, with ss emitting a non-empty diagnostic banner and netstat reporting 0.0.0.0:8080 LISTEN, port_listen_state 8080 still returns unknown and lets startup reach the later bind failure. Please capture the parser result and return only for busy or free; continue to netstat on unknown, with a regression covering this fallback.

Correct — the branch returned unconditionally, so a ss run that produced unusable output ended the search with a working netstat sitting right behind it. Fixed in d93b6f9d: the parser result is captured and only an actual answer returns.

if command_available "ss" && out=$(ss -H -ltn 2>/dev/null); then
    if [[ -z "$out" ]]; then
        echo "free"
        return 0
    fi
    state=$(echo "$out" | awk -v port="$port" -v sep=":" -v want_listen=0 "$parser")
    case "$state" in
        busy|free) echo "$state"; return 0 ;;
    esac
fi
# netstat is tried next, same shape

case busy|free rather than != unknown so an awk that dies and prints nothing also falls through instead of echoing an empty state.

One thing came out of your Docker comment that had to be fixed here too, or the image fix would only have been half of one. ss -H -ltn on a host with no listeners exits 0 and prints nothing, and a fresh container is exactly that. Treating empty as failure meant even an image with iproute2 would warn on every clean start. -H suppresses the header, so there is no header to lose: a zero exit with no output is a positive "no TCP listeners", not an unreadable table. That is now the one case where empty is an answer, and it is the only reason port_listen_state returns free instead of unknown in the new image-build assertion.

Both netstat branches still print headers the parser drops, so an empty result there stays unknown. That is narrowed in the TODO(check_port) above the function rather than claimed as solved.

Regressions added (section 2 of the suite):

PASS  ss empty output is free
PASS  ss unparseable output is unknown
PASS  unparseable ss falls back to netstat
PASS  netstat fallback can also report free
PASS  failed ss falls back to netstat

Restoring the early return 0 fails exactly the two fallback cases; restoring unknown-on-empty fails exactly one.

🧹 This comment still describes an ss/netstat//dev/tcp fallback chain, but the exact-head implementation contains no /dev/tcp branch and returns unknown when neither socket-table tool is usable. Please update this and the matching comments below to describe the actual ss/netstat behavior.

Right, /dev/tcp is left over from an earlier revision that had a bounded-connect fallback; that branch was removed and the comments were not. Fixed in d93b6f9d, all three sites:

-# Validates ss/netstat//dev/tcp replacement for lsof
+# Validates the ss/netstat port preflight that replaced lsof

-# Note: lsof removed from prerequisites (replaced with ss/netstat//dev/tcp in check_port).
+# Note: lsof removed from prerequisites; check_port now uses ss, falling back
+# to netstat, and warns without blocking when neither can answer.

grep -rn "dev/tcp" over the tree is now empty.

⚠️ Bounding each curl request does not make wait_for_startup honor its overall timeout: after an immediate failed probe the loop always sleeps two seconds before re-reading the clock. With timeout_s=1, an immediate curl failure still returns after about two seconds, and the new test checks only the curl flags rather than elapsed time. Please recompute the remaining deadline before sleeping, cap the sleep to that remainder, and assert the end-to-end duration.

Confirmed. Bounding each request bounds the request, not the loop — the pause was a flat sleep 2 taken before the clock was re-read, so timeout_s=1 ran for about 2s. I had noted the overshoot in a TODO(wait_for_startup) and left it; you are right that documenting it is not the same as honouring the timeout. Fixed in d93b6f9d:

now_s=$(date '+%s')
local sleep_s=$((stop_s - now_s))
[ "$sleep_s" -le 0 ] && break
[ "$sleep_s" -gt 2 ] && sleep_s=2
sleep "$sleep_s"
now_s=$(date '+%s')

The break matters as much as the cap: with the deadline spent, falling through to the while guard on a whole-second clock would spin on repeated instant probes until the second ticked over.

On the assertion — you asked for elapsed time, and the suite now checks it, but the load-bearing check is the other one. Wall-clock at date +%s resolution cannot separate a 1s run from a 2s run reliably, so both are asserted: sleep is shimmed to record what was requested and then take it for real, so the duration stays a real measurement.

PASS  retry sleeps stay inside the 1s deadline
PASS  wait_for_startup returns within the deadline (1s)

Total requested sleep must be <= timeout_s, which is exact — restoring sleep 2 fails it every time, while the elapsed check alone would be a coin flip on the second boundary. Ran it five times, 1s each time.

wait_for_shutdown has the same fixed-pause-then-check shape and the same overrun. Left alone with a TODO(wait_for_shutdown) pointing at this fix, since it is untouched by this PR and widening the diff is the thing you asked me not to do. Happy to fix it here if you would rather.

⚠️ The overall deadline can still be exceeded at its boundary. The inclusive loop permits another iteration when now_s == stop_s, then this line converts the expired remain_s=0 into a fresh one-second curl budget. Two independent exact-head lanes reproduced two probes for timeout_s=1; when the deadline-edge probe consumed its advertised budget, elapsed time was about two seconds. Please refresh the clock before every curl and stop when no positive budget remains instead of clamping zero to one, then add a regression proving no probe begins at the deadline.

⚠️ The checksum repair is still racy across concurrent starts. Two callers can both verify the same corrupt destination; one can download and atomically install a valid replacement at line 342, after which the other executes this stale removal and deletes the valid file. Please leave the destination in place while downloading and verifying a private temporary file, atomically replace it only after success, and use a per-destination lock if callers require stable success semantics; add a coordinated two-caller regression.

⚠️ This image-level port-preflight check executes the changed bin/util.sh, but the workflow's PR filter still includes only Dockerfiles and .dockerignore. A later PR changing only the probed utility will skip the only check that proves the built image has a compatible socket-table tool. Please add hugegraph-server/hugegraph-dist/src/assembly/static/bin/util.sh to pull_request.paths.

⚠️ Both Linux and macOS CI invoke this required contract test with an explicit production path, yet a missing or moved util.sh exits successfully without running any assertion. That can turn a broken test wiring change into a green check. Please fail when the explicitly selected utility is absent; reserve a skip result for a clearly optional invocation mode.